Original version by Jon Lansdell and Nigel Humphreys
3.1 updates by Greg Sutton
Introduction
The aim of this document and it's associated application with code is to give an example of creating a Scriptable Application. A scriptable application goes far beyond supporting just the basic four events of the Required Suite (Open Application, Open Documents, Print Documents and Quit Application).
This latest version of 7Edit has been designed to be very similar to the Scriptable Text Editor. The example may not be as fully scriptable as the Scriptable Text Editor but it should give you good idea of how to make your application scriptable. In particular it shows you how to handle the 'whose' clause in AppleScript.
This version of 7Edit also demonstrates QuickDraw GX printing and Drag Manager Support.
In this document I shall assume that you know or understand AppleScript as this will form a basis of why and how certain AppleEvents are supported. If you do not know anything of AppleScript then there are quite a few good books on the subject.
I also highly recommend that you do the Developer University Mini Course - Apple Events/AppleScript Programming Tutorial. This course goes into more general detail than this documentation. There are also some good articles in develop about the Object Model, designing your scripting language and supporting suites. See the references at the end of this document.
How to use 7Edit
This application is basically a simple text editing program. The major difference between this application and other text editing programs, such as Simple Text, is that 7Edit is scriptable. This means that the program can be controlled through the scripting language AppleScript. So, for example, the following script would return a list of every word in the front window of 7Edit which contained the letter k:
tell application "7Edit"
get every word of document 1 where it contains "k"
end tell
There are some sample scripts in the ' Example Scripts' folder. Each of these scripts contains a number of scripts to try out, most of them are commented out (using '--'). To run a script, open the file with Script Editor and comment out all the lines except the line you want and run it.
Note: The name of the application may vary depending on the version of 7Edit you run e.g. the Metrowerks Power PC version is called "7Edit.MW.PPC". If you find you are not getting the results you suspect make sure another version of 7Edit hasn't been launched in the background.
Building the Application
MenuScripter compiles under :
Metrowerks CodeWarrior 7 68K and PPC
Symantec C++ 8.0.1
Symantec 7.0.4
MPW E.T.O. #18- 'Latest MPW': MPW C, PPCC, Symantec C++ for MPW and MrC.
- Symantec C++ for Macintosh build notes
The Symantec environments are using a slightly older version of the Universal Interfaces than MPW and CodeWarrior. You will need to use a later version of the Universal Interfaces than is provided with the Symantec products, or make some changes to the source code. To change the Universal Interfaces, simply place brackets around the existing folder and place the folder containing the later version into the same folder as the existing ones. The brackets will prevent the development environment from using the files contained within the old folder. The later version can be retrieved off the latest ETO CD, it's the 'CIncludes' folder in the Latest MPW:
You will also need to copy another couple of folders into this folder, these are 'GX Libraries' and 'GX Compatibility Interfaces':
'MPW Pro:Essentials:U.S. System Software:System Extensions:QuickDraw GX:GX Libraries'
'MPW Pro:Essentials:U.S. System Software:System Extensions:QuickDraw GX:GX Compatibility Interfaces'
Lastly you need to make sure that you have the 'QuickDrawGXLib.xcoff' library when compiling with Symantec C++ 8.0.1. This should be put in Symantec's 'PPC Libraries' folder and the library can be found from the following path:
It is recommended that you use precompiled headers with Symantec C++ 8.0.1. This will speed compilation and decrease the memory needed. Included in the project is 'Mac #includes.c' to precompile a new 'PPC Macheaders' select this file and select Precompile or Precompile As… from the Build menu.
- MPW build notes
Two MPW make files are included: to build a 68K and a 'fat' version using 'Latest MPW' from ETO#18. The make file for the 68K version of 7Edit is set up to use the default, which is MPW C. The 'fat' make file uses SC and MrC and is designed to compile with the interfaces and libraries from 'Latest MPW'. Instructions are provided on ETO for installing Symantec C++ for MPW 8.0.1 (do not use the version from 'PreRelease MPW' with the 'Latest MPW' interfaces and libraries) and using MrC with 'Latest MPW'. When using SC, you will need to alter the compiler options as appropriate and use the 'Latest MPW' interfaces and libraries rather than SCLibraries and SCIncludes.
To compile either the 68K or 'fat' version of 7Edit under MPW you will need to copy the 'GX Libraries' and 'GX Compatibility Interfaces' from the QuickDraw GX release (see notes above for Symantec C++ for Macintosh) into your MPW CIncludes folder. You will also need to copy the version of 'DragLib' included with this project into your MPW:Libraries:Shared Libraries folder. Using older versions of DragLib will produce link errors, since a routine used by 7Edit is not included in earlier versions of DragLib.
How Does it Work?
I think the best way to show you how events are handled is to take you through a few example scripts explaining things as I go.
Select Example
The select event is a good event to begin with, the routines associated with it are used in many events and it can take varying types of parameters. So let's start with the following script:
tell application "7Edit"
select window 2
end tell
The expected result of this script is to bring the window behind the front window i.e. window 2 to the front, or if there is only one window complain that the window does not exist. 7Edit does this, but what goes on in the background?
First of all we'll take a look at what the Apple Event Registry, well the Apple Event Registry Errata v3 at the moment, has to say about the select event.
Event Class: kAEMiscStandards
Event ID: kAESelect = 'slct'
Parameters
keyDirectObject
Driescption: Specifies the objects to be selected
Desc Type: typeObjectSpecifier
Required? Yes
Reply
keyAEErrorNumber
keyAEErrorString
This tells us that it is in the Miscellaneous Suite and that you can use kAESelect to refer to it within your program (as long as you include the appropriate header which in this case is 'AERegistry.h'). The first thing that needs to be done is to tell the Object Support Library that your application can handle this event. This is done by installing a handler, or a routine that gets called whenever your application gets one of these events. In 7Edit this is done in the InitAppleEvents() routine:
If we look back at the Apple Event Registry definition we see that we expect a keyDirectObject parameter. So the first thing we do is get that out of the apple event. If we get a keyDirectObject descriptor then SelectDesc() is called. It doesn't make sense to select nothing, so we create a text descriptor and this gets put in the reply so that a user can understand the error instead of getting something baffling (something that should be done more than it is in 7Edit). Lastly we tidy up by disposing of any descriptors we've created.
The next routine to take a look at is SelectDesc().
The first thing this routine does is check to see if the descriptor which we got as the direct parameter is an object specifier or not. In the case of an event sent due to our script, it will be. It will be an object specifier which specifies window two of our document. The Object Support Library can resolve an object specifier, with AEResolve(), into a descriptor that your application understands by using accessors that you've installed.
Let's digress and see how we would create an object specifier for a window. There is a routine that does do this for recording and reply purposes. Think of an object specifier as a description that AppleScript can take and convert into a readable form.
We get the index of the window first - checking that it does actually exist. A descriptor for that index is then created and this is used in the creation of the object specifier. We use cWindow to say that this object is a window. The nullDesc is for the object that contains this window, a descriptor of typeNull describes the application itself in an object specifier. The formAbsolutePosition parameter says that the descriptor we supply to describe the object is an absolute position descriptor i.e. it is an index to the window. There are also other forms of descriptors, such as formName and formRange but we'll go into these later.
So an object specifier is a reference to an object in our application. When you see, in an AppleScript definition, that a handler requires a reference as a parameter. The parameter will be passed to that application as an object specifier. So back to what accessors do. Accessors are routines in your application that convert object specifiers into internal representations that your application can use. So the kind of accessor we want is one that takes an object specifier for a window and returns a WindowPtr, so that we can use the Toolbox routine BringToFront() to select our window.
We install an accessor routine that can do this in the InstallAccessors() routine.
Installing this accessor tells the Object Support Library that if it wants to resolve an object specifier for a window from the container class typeNull (i.e. the application) into a form our application understands, then call the WindowFromNullAccessor() routine.
So the WindowFromNullAccessor() routine will be called by the Object Support Library when we call AEResolve() in our SelectDesc() routine. How does WindowFromNullAccessor() get a WindowPtr for us?
WindowFromNullAccessor() checks that it can handle the type of class wanted and also that it can do it from the given container type. The routine then calls a routine that can deal with the form of the data in the selectionData descriptor. 7Edit only handles two types of object specifier forms for a window. Earlier we saw how formAbsolutePosition was where the window was specified by an index. The formName, as you may expect ,is where the window (or object) is specified by it's name, this allows the following script to be resolved:
tell application "7Edit"
select window "Untitled"
end tell
When we look at the WindowFormAbsolutePosition() routine we see that it's actually a bit more complicated than you'd expect. This is because the actual definition for formAbsolutePosition is that it specifies the position of an element via an index in relation to the beginning or end of it's container.
This means that all of the following scripts will also have their object specifier resolved through formAbsolutePosition:
tell application "7Edit" to select first window
tell application "7Edit" to select last window
tell application "7Edit" to select middle window
tell application "7Edit" to select some window
tell application "7Edit" to select every window
The odd script from this lot is the last one, as this can result in more than one window. The way we deal with this is to create a list that holds a description for each window. The last script will actually produce an error - this is because it doesn't make sense to select every window because only one window can ever be at the front. The following script makes perfect sense though:
tell application "7Edit" to close every window
If you look back at the SelectDesc() routine you'll see that if the descriptor is a list then it returns an error. However, if you look at the CloseDesc() routine you'll see that it actually recursively calls itself for every descriptor in the list given. Doing it in this way allows for lists within lists which you can get in more complicated scripts.
The WindowFormAbsolutePosition() routine also needs to be able to handle negative indexes. A negative index implies that the index should be taken backwards from the last window instead of forwards from the first window. This allows us to resolve the script below:
tell application "7Edit" to select window -1
We still haven't seen the WindowPtr that we need to be able to call BringToFront(). This is bundled up in the result descriptor of the GetDescOfNthWindow() routine.
Here we see that we stick the WindowPtr into a WindowToken. Tokens are the way you represent all the information you need to identify an object internally. They can be very complicated if you like, although none are in 7Edit. Here is how we define a WindowToken in 'SVToken.h':
struct WindowToken
{
WindowPtr tokenWindow;
};
typedef struct WindowToken WindowToken;
It is simple. This is because all our application needs to identify a window is it's WindowPtr. So this is our internal represenation for cWindow.
Right, back to the SelectDesc() routine. We've now seen how the object specifier for the window was resolved into a descriptor of type typeMyWndw by calling AEResolve(). The routine then switches on this type and calls SelectWindowDesc():
This routine just checks that it is a window descriptor and if it is gets the WindowToken out of the descriptor. The token is then passed onto SelectWindowToken():
OSErr SelectWindowToken(WindowToken* theToken)
{
OSErr err = noErr;
if (! theToken->tokenWindow)
return(errAENoSuchObject);
BringToFront(theToken->tokenWindow);
return(err);
}
This routine finally calls BringToFront() to select the window.
Get Data Example
The next example script to look at is a script that gets a property from an object.
tell application "7Edit"
get length of last word of document 1
end tell
Again of we have a look at what the Apple Event Registry says about Get Data, it goes something like the following.
Event Class: kAECoreSuite
Event ID: kAEGetData
Parameters
keyDirectObject
Description: The set of objects whose data is to be returned
Desc Type: typeObjectSpecifier
Required or Optional? Required
keyAERequestedType
Description: A descriptor list containing typeType descriptor records.
Descriptor Type: typeAEList
Required or Optional? Optional (default value: the default descriptor type of the
objects whose data is to be returned)
Reply
keyAEErrorNumber
keyAEErrorString
The main difference between Get Data and Select is that Get Data can have an optional parameter. Not that the optional parameter is always quite as the Apple Event Registry says. Anyway we won't use the optional parameter in this example. If you want to see a better example of optional parameters look at the DoNewElement() routine in 'SVAECreate.c'.
There is a handler installed in InitAppleEvents() that tells the Object Support Library (OSL) which routine to call when we get a get data event.
The routine DoGetData() retrieves the direct parameter and passes it onto HandleGetData(). HandleGetData() then resolves the direct parameter because it is an object specifier. However this object specifier is different from the specifier in the select example because it specifies a property of an element.
So how is the object specifier resolved? When an object specifier is resolved it effectively starts at the right of the specifier and works left. So the first part that the accessors need to resolve is 'document 1'. If we have a look at the accessors installed in InstallAccessors() we see that this is handled by the same routine as 'window 1' i.e. WindowFromNullAccessor().
We saw in the select example that this returned a descriptor of type typeMyWndw. So once this is resolved the Object Support Library tries to resolve 'every word of document 1' where 'document 1' has been resolved to typeMyWndw. Looking again at the accessors installed in InstallAccessors(), you can see that there is the following accessor:
We saw earlier how a window was represented internally by a WindowToken, but what about the internal representation for a word, a character or a paragraph? Do we need a seperate type of token for each of these? As it turns out we can represent any kind of text internally with one type of token, our TextToken.
struct TextToken
{
WindowPtr tokenWindow;
short tokenOffset;
short tokenLength;
};
typedef struct TextToken TextToken;
We need a window, from which we can get the text edit handle, an offset into it's hText handle, and the length of the text. When it comes to turning a TextToken into an object specifier there is a routine GetTextTokenObjectSpecifier(), in 'SVAETextUtils.c', which tries it's best to make the most meaningful object specifier.
You may expect that we would have an accessor like TextElemFromWindowAccessor() that should be called at this stage after all 'document 1' resolved to typeMyWndw. This was true in the previous version of 7Edit. Now there is a coercion handler installed which can coerce a descriptor of typeMyWndw to a descriptor of type typeMyText. The resulting descriptor is a TextToken that includes all the text in the window.
When TextElemFromTextAccessor() is called to resolve 'last word of document 1' the window descriptor gets coerced into a TextToken. 'Last word' is of formAbsolutePosition so the routine TextFormRelativePosition() is called where the words in the container descriptor, 'document 1', are counted and a descriptor to the last word is created. This descriptor is of typeMyText.
Back to looking at the accessors installed in InstallAccessors(). This time we want a property from a TextToken descriptor of typeMyText. We can see that the accessor we want is:
We need this token because a TextToken doesn't hold enough information. We need to know the text it refers to and the property of it. So we declare a TextPropToken as follows:
struct TextPropToken
{
TextToken tokenTextToken;
DescType tokenProperty;
};
typedef struct TextPropToken TextPropToken;
So PropertyFromTextAccessor() finally resolves the object specifier we were passed, 'last word of document 1' in to a TextPropToken descriptor of type typeMyTextProp. Now we can go back to HandleGetData().
Where we switch to GetTextProperty() to get the actual information rather than just an internal reference to that information. GetTextProperty() eventually switches on the property type in the TextPropToken and simply returns a descriptor for the length of the token which is the length of the word.
Now what would happen if we had the following script instead?
tell application "7Edit"
get length of every word of document 1
end tell
On resolving up to 'every word of document 1' we would have a list of TextToken descriptors instead of just a single one. We then have to apply the length property to every item in the list. What we have done is install another accessor which is called when the Object Support Library wants to resolve a property from a list:
This routine then steps through the list and converts any non property tokens into property tokens in much the same way as we converted a TextToken into a TextPropToken in PropertyFromTextAccessor(). The final result is then a list of property values. Try it out.
